Shipping methods

Handling shipping is a crucial part of any e-commerce solution. This section will guide you through fetching available shipping methods, including pick-up points, and selecting a shipping method using the Afosto Storefront JavaScript Client. You'll learn how to perform these actions in a custom checkout process.

Fetch Available Shipping Methods

We can fetch the shipping methods using the cart. This ensures we only get methods that are applicable to the current cart and its information. This way, only the methods available for the selected shipping country will be returned. It also calculates any pricing rules for the shipping methods, adding or removing shipping fees.

Here is a GraphQL query example to fetch available shipping methods, including pick-up points based on a postal code and country code. Without a postal code and country code, the pickup points with throw an error that these are required.

1import { gql } from '@afosto/storefront';
2
3const query = gql`
4  query getCart($id: String!, $country_code: String!, $postal_code: String!) {
5    cart(id: $id) {
6      options {
7        shipping {
8          methods {
9            id
10            name
11            description
12            instruction
13            carrier
14            is_pickup_point
15            pickup_points(
16              country_code: $country_code
17              postal_code: $postal_code
18            ) {
19              id
20              name
21              distance
22              address {
23                country_code
24                administrative_area
25                locality
26                postal_code
27                address_line_1
28                address_line_2
29                thoroughfare
30                premise_number
31                premise_number_suffix
32              }
33            }
34            pricing {
35              fixed
36              percentage
37            }
38          }
39        }
40      }
41    }
42  }
43`;
44
45const variables = {
46  id: 'my_cart_token',
47  countryCode: 'NL',
48  postalCode: '9723JA',
49};
50
51const response = await client.query(query, variables);

Select a shipping method

When the customer has made its decision, we can add the shipping method to the cart. This can be done using the example below.

1import { gql } from '@afosto/graphql-client';
2import CoreProjectionFields from '../CoreProjectionFieldsFragment';
3
4const AddShippingMethodToCart = gql`
5  mutation AddShippingMethodToCart($shipping_method_payload: AddShippingMethodToCartInput!) {
6    addShippingMethodToCart(input: $shipping_method_payload) {
7      cart {
8        ...CoreProjectionFields
9        id
10        delivery {
11          method {
12            id
13            name
14          }
15        }
16      }
17    }
18  }
19`;
20
21const variables = {
22  shipping_method_payload: {
23    cartId: 'my_cart_token',
24    methodId: 'selected_shipping_method_id',
25  },
26};
27
28const response = await client.query(AddShippingMethodToCart, variables);

This query also includes a fragment to get information for the projection. The CoreProjectionFields fragment includes all the information you need to show a cost summary. The summary keeps the customer informed about extra costs added by their choices. In the hosted checkout we include this fragment in every step so keep the summary up to date.

Pickup points

Some carriers provide methods that are pickup points. With these methods, a customer can select a nearby pickup point to deliver their order to. In the first example, we fetch the pickup points for all methods that have them. Using that data, you can present the options to the customer in your checkout.

Search pickup points by postal code

If you want to offer your customer the option to search for pick-up points based on a postal code, you can use the following query. Adding a search field in your checkout that uses this query will help the customer select the best pickup point for them.

1import { gql } from '@afosto/graphql-client';
2
3const getPickupPointsForCartQuery = gql`
4  query GetPickupPointsForCart($id: String!, $postal_code: String!, $country_code: String!) {
5    cart(id: $id) {
6      id
7      delivery {
8        method {
9          pickup_points(country_code: $country_code, postal_code: $postal_code) {
10            id
11            name
12            carrier
13            distance
14            address {
15              country_code
16              administrative_area
17              locality
18              postal_code
19              address_line_1
20              address_line_2
21              thoroughfare
22              premise_number
23              premise_number_suffix
24            }
25          }
26        }
27      }
28    }
29  }
30`;
31
32const variables = {
33  id: 'my_cart_token',
34  countryCode: 'NL',
35  postalCode: '9712HW', // Update this based on user input
36};
37
38const response = await client.query(getPickupPointsForCartQuery, variables);

Selecting the pickup point

To select the pickup point for a method, we need to do a separate mutation. This needs to be done after selecting the shipping method.

1import { gql } from '@afosto/graphql-client';
2import CoreProjectionFields from '../CoreProjectionFieldsFragment';
3
4const addPickupPointToCartMutation = gql`
5  ${CoreProjectionFields}
6  mutation AddPickUpPointToCart($pickup_point_payload: AddPickUpPointToCartInput!) {
7    addPickUpPointToCart(input: $pickup_point_payload) {
8      cart {
9        ...CoreProjectionFields
10        delivery {
11          method {
12            id
13            name
14          }
15          pickup_point {
16            id
17            name
18          }
19        }
20      }
21    }
22  }
23`;
24
25export default addPickupPointToCartMutation;

By following these steps, you'll be able to effectively manage shipping methods in your custom checkout process with the Afosto Storefront JavaScript Client. Next step is selecting a payment method.